home *** CD-ROM | disk | FTP | other *** search
/ Technotools / Technotools (Chestnut CD-ROM)(1993).ISO / lang_c / api_tool / assembly.doc next >
Text File  |  1988-12-26  |  10KB  |  262 lines
  1.                       API Details
  2.  
  3. In order for you to get a feel for the power built-in to each and every
  4. DESQview, we've included a short description about each API command.
  5.  
  6. The DESQview 2.2 API is an objected-oriented interface. The data structures
  7. DESQview uses to represent windows, mailboxes, etc. are called "objects".
  8. A call to the API involves "sending a message" to an object, indicating
  9. which of several operations you want performed on that data structure.
  10. This is referred to as the "send interface". Almost the entire API
  11. consists of sending one of 34 messages to one of 7 different object types.
  12.  
  13. The DESQview 2.2 API also has a non-object-oriented interface called
  14. the "direct call interface". This is the small subset of API functions
  15. that are not, by nature, object oriented or that are convenient alternatives
  16. to the send interface.
  17.  
  18. The DESQview 2.2 API has a concise way of encoding a complete description
  19. of a window so that a single call to the API can create the window,
  20. fill it with the desired information, size and position it on the
  21. display, and define fields that interact with the user. All this is
  22. done using "Window Streams".
  23.  
  24. So that you can interrogate a window for its current contents, position,
  25. etc., the DESQview 2.2 API also has "Query Streams". In fact, any
  26. window parameter that can be set by a Window Stream can be read by
  27. a Query Stream.
  28.  
  29. DESQview calls the portion of itself that interfaces with the user
  30. the "Window Manager". Each time a user presses the DESQ key (normally
  31. the Alt key) and makes a menu selection, it is the Window Manager
  32. that opens, switches, rearranges and closes windows, transfers data,
  33. displays help, or quits DESQview. In order for an application to have
  34. the same power as the user, the DESQview 2.2 API has "Manager Streams".
  35. Manager Streams enable an application to interact with the Window
  36. Manager.
  37.  
  38. Using Manager Streams an application can, for example, ask the Window
  39. Manager to make one of its windows the topmost window in the system,
  40. disallow any resizing of  the window by the user, and even notify
  41. the application if the user tries to close the window. Using Manager
  42. Streams an application can disallow use of the DESQview menu and DESQview
  43. submenus.
  44.  
  45. But, there's still even more to the DESQview 2.2 API. DESQview provides
  46. a comprehensive set of functions for simplifying the job of interfacing
  47. with the user. Instead of dealing with user input a single character
  48. at a time, your application can present entire menus, dialogue boxes,
  49. help screens to DESQview and get back the resulting user input. Common
  50. functions such as cursor control, insertion and deletion of characters,
  51. tracking the mouse, and selection from option lists are performed
  52. by DESQview. DESQview performs these functions under control of a
  53. data structure called the "Field Table".
  54.  
  55. Information about a window's size, position, contents and Field Table
  56. can be combined together into "Panels". Panels can be stored on disk
  57. or in memory for later display. Panels can be constructed manually
  58. or via the DESQview API Panel Design Tool.
  59.  
  60.  
  61. DESQview 2.2 API Commands:
  62.  
  63. Send Interface Commands
  64.  
  65. WINDOW Objects
  66.  
  67. ADDTO     write characters &attributes to a window
  68. AT        position the logical cursor
  69. EOF       return TRUE if cursor is past end window
  70. ERASE     clear a window
  71. FREE      close and free a window or a task
  72. HANDLE    return handle of current task's window
  73. LEN       return # characters/line in logical window
  74. NEW       create a new window or task
  75. OPEN      fill a window with a given character
  76. READ      read the next logical line from a window
  77. READN     read the next n characters/attributes
  78. REDRAW    redraw a window
  79. SIZEOF    return total # characters/logical window
  80. SUBFROM   write attributes to a window
  81. WRITE     write characters and/or command streams
  82.  
  83.  
  84. KEYBOARD Objects
  85.  
  86. ADDTO     set keyboard control flags
  87. CLOSE     close a keyboard object
  88. ERASE     discard all input queued to Keyboard
  89. FREE      free a Keyboard object
  90. GETFLAGS  get keyboard control flags
  91. GETPRI    get objectq priority level of keyboard
  92. HANDLE    return handle of task's default keybd
  93. NEW       create a new Keyboard object
  94. OPEN      attach a Keyboard to a window
  95. READ      get the next input from the Keyboard
  96. SETESC    intercept keystrokes to input fields
  97. SETFLAGS  replace keyboard control flags
  98. SETPRI    set objectq priority level of keyboard
  99. SIZEOF    return #  of input buffers queued
  100. STATUS    get the scan code for the last key read
  101. SUBFROM   clear keyboard control flags
  102. WRITE     add input buffer to Keyboard queue
  103.  
  104.  
  105. MAILBOX Objects
  106.  
  107. ADDR      return tender of the last message READ
  108. ADDTO     send a message and status by value
  109. CLOSE     close a Mailbox
  110. ERASE     discard all queued messages
  111. FREE      frees a Mailbox
  112. GETFLAGS  get mailbox control flags
  113. GETPRI    get objectq priority level of mailbox
  114. HANDLE    return handle of task's default mailbox
  115. LOCK      request exclusive access to a resource
  116. NEW       create a new Mailbox
  117. OPEN      open a Mailbox for input
  118. READ      get the next message from the queue
  119. SETFLAGS  replace mailbox control flags
  120. SETPRI    set objectq priority level of mailbox
  121. SETNAME   assign a name to a Mailbox
  122. SIZEOF    return the #  of messages in the queue
  123. STATUS    return status of the last message READ
  124. SUBFROM   send a message &status by reference
  125. WRITE     send a message by value with status=0
  126.  
  127.  
  128. OBJECTQ Objects
  129.  
  130. CLOSE     Close an Objectq
  131. ERASE     remove all objects from the queue
  132. HANDLE    return the handle of a task's Objectq
  133. OPEN      open the Objectq
  134. READ      wait for input from any open object
  135. SIZEOF    return the number of objects queued
  136. STATUS    return whether or not  Objectq is open
  137. SUBFROM   remove specific object from queue
  138. WRITE     add an object to the Objectq
  139.  
  140.  
  141. PANEL Objects
  142.  
  143. APPLY     display a particular panel
  144. CLOSE     close a panel object
  145. DIR       return a pointer to the panel directory
  146. FREE      free a panel object
  147. NEW       create a panel object
  148. OPEN      associate panel object with a panel file
  149. SIZEOF    return the # of panels in a panel file
  150. STATUS    verify success of an OPEN or APPLY
  151.  
  152.  
  153. POINTER Objects
  154.  
  155. ADDTO     set pointer control flags
  156. CLOSE     stop taking pointer input
  157. ERASE     discard all pointer messages
  158. FREE      free a Pointer object
  159. GETFLAGS  get pointer control flags
  160. GETPRI    get objectq priority level of pointer
  161. GETSCALE  return the current scaling factors
  162. NEW       create a new Pointer object
  163. OPEN      start taking Pointer input for window
  164. READ      wait for the next pointer message
  165. SETFLAGS  replace pointer control flags
  166. SETPRI    set objectq priority level of pointer
  167. SETSCALE  set the current scaling factors
  168. SIZEOF    return the number of messages queued
  169. STATUS    return the status of the last message
  170. SUBFROM   reset pointer control flags
  171. WRITE     move the pointer to a specified position
  172.  
  173.  
  174. TIMER Objects
  175.  
  176. ADDTO     start a timer for a specified interval
  177. CLOSE     close a Timer object
  178. ERASE     cancel the current timer interval
  179. FREE      free a Timer object
  180. GETPRI    get objectq priority level of timer
  181. LEN       return time remaining before expiration
  182. NEW       create a new Timer object
  183. OPEN      open a Timer object
  184. READ      wait for the current timer to expire
  185. SETPRI    set objectq priority level of timer
  186. SIZEOF    return elapsed time since timer started
  187. STATUS    return the status of the Timer object
  188. WRITE     start a timer to end at a specified time
  189.  
  190.  
  191. Direct Call Interface Commands
  192.  
  193. APILEVEL  define minimum API level required
  194. APPNUM    get the current application's number
  195. ASSERTMAP get current mapping context and set new one
  196. BEGINC    begin critical region
  197. CSTYLE    use C language style control codes
  198. DBGPOKE   poke debug information onto display
  199. DISPEROR  display an error message window
  200. DVPRESENT determine if DESQview is present
  201. ENDC      end critical region
  202. FINDMAIL  find a mailbox by name
  203. FREEBIT   undefine second-level interrupt handler
  204. GETBIT    define a second-level interrupt handler
  205. GETBUF    get address of a Logical Window Buffer
  206. GETCRIT   get critical region nesting level
  207. GETERROR  get error handling level of current task
  208. GETMEM    allocate buffer from System Memory
  209. ISOBJ     determine if a handle is valid
  210. JUSTIFY   turn off/on automatic justification
  211. KMOUSE    control the keyboard mouse
  212. LOCATE    find window at given screen location
  213. NEWPROC   start a new process
  214. OBJTYPE   determine the object type of a given handle
  215. OSTACK    switch to task's internal stack
  216. PAUSE     relinquish control to other tasks
  217. PGMINT    interrupt another task
  218. POSTTASK  awaken task by posting its Objectq
  219. POSWIN    position a window on the display
  220. PRINTC    display a character in a window
  221. PUSHKEY   push key into keyboard input stream
  222. PUTMEM    free a buffer allocated by GETMEM
  223. SETBIT    schedule a second-level interrupt handler
  224. SETERROR  set error handling level of current task
  225. SHADOW    get window buffer and start shadowing
  226. SOUND     make a sound
  227. START     start a task that was previously stopped
  228. STOP      stop a task until START is called
  229. UPDATE    update a portion of a window
  230. USTACK    switch off task's internal stack
  231.  
  232.  
  233. Window Stream Commands
  234.  
  235. 00 to 9F  print strings (attributes,characters,blanks) to window
  236. A0 to CF  change size/ position of a window
  237. D0 to DF  set options for appearance of window:
  238.           frames, color, show/hide window, display of control characters
  239. E0 to EF  perform immediate actions:
  240.           clearing, scrolling, recoloring, redrawing window;
  241.           create new windows &repeat command sequences
  242. F0 to FF  define, read, write fields within window.
  243.  
  244.  
  245. Query Stream Commands
  246.  
  247. same as Window Stream commands
  248.  
  249.  
  250. Manager Streams
  251.  
  252. 00 to 3F  Allows specific DESQview commands:
  253.           move & resize window, scroll data, hide, rearrange program,
  254.           suspend application, display DESQview menu
  255. 40 to 71  notify application on specific DESQview commands.
  256. 84 to 8B  specify environment of window:
  257.           suspend application when it is in background,
  258.           set application's asynchronous notification.
  259. AC to BF  enable/disable DESQview extensions.
  260. C0 to FF  reorder, hide, unhide, suspend resume
  261.           applications.
  262.